---
title: API Reference
description: Complete REST API documentation for Stack Auth
full: true
---

Stack offers a REST API for backends & frontends of any programming language or framework. This API is used to authenticate users, manage user data, and more.

## Authentication

Stack Auth uses different authentication patterns depending on whether you're making requests from client-side code (browser, mobile app) or server-side code (your backend).

<Info type="warning">
**Security Critical**: Never expose your secret server key (`ssk_...`) in client-side code, browser requests, or any publicly accessible location. Server keys should only be used in secure backend environments.
</Info>

### Client-Side Authentication

For requests from browsers, mobile apps, or other client-side environments:

```http
curl https://api.stack-auth.com/api/v1/ \
     -H "X-Stack-Access-Type: client" \
     -H "X-Stack-Project-Id: <your project UUID>" \
     -H "X-Stack-Publishable-Client-Key: pck_<your publishable client key>" \
     -H "X-Stack-Access-Token: <the current user's access token>"
```

### Server-Side Authentication

For requests from your secure backend server:

```http
curl https://api.stack-auth.com/api/v1/ \
     -H "X-Stack-Access-Type: server" \
     -H "X-Stack-Project-Id: <your project UUID>" \
     -H "X-Stack-Secret-Server-Key: ssk_<your secret server key>"
```

### Authentication Headers

| Header | Type | Used In | Description |
| ------ | ---- | ------- | ----------- |
| `X-Stack-Access-Type` | "client" \| "server" | Both | Required. Use "client" for frontend/browser requests, "server" for backend requests. |
| `X-Stack-Project-Id` | UUID | Both | Required. Your project ID from the Stack dashboard. |
| `X-Stack-Publishable-Client-Key` | string | Client only | Required for client access. Safe to expose in frontend code. Starts with `pck_`. |
| `X-Stack-Secret-Server-Key` | string | Server only | Required for server access. **Never expose in client code**. Starts with `ssk_`. |
| `X-Stack-Access-Token` | string | Client only | Optional. The current user's access token. Used to act on behalf of a specific user. |

<Info type="info">
{/* IF_PLATFORM python */}
To see how to use these headers in various programming languages, see the [Getting Started guide](./../getting-started/setup.mdx).
{/* ELSE_IF_PLATFORM js-like */}
To see how to use these headers in various programming languages, see the [examples](./../concepts/backend-integration.mdx).
{/* END_IF_PLATFORM */}
</Info>

## Getting Started

<Steps>
  <Step>
    **Choose the right API**: Select the API category that matches your use case from the cards above
  </Step>
  <Step>
    **Set up authentication**: Configure the appropriate authentication method (sessions, API keys, or webhook verification)
  </Step>
  <Step>
    **Make requests**: Use the documented endpoints with proper authentication headers
  </Step>
  <Step>
    **Handle responses**: Process the API responses according to the documentation and error handling guidelines
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Which languages are supported?">
    Any language that has the ability to send HTTP requests can use the Stack REST API. This includes JavaScript, Python, Ruby, Java, Go, C#, Dart, and many more.
  </Accordion>
  
  <Accordion title="Should I use client or server access type?">
    **Client access type** (`X-Stack-Access-Type: client`) is for client-side applications like browsers and mobile apps. Client APIs can only read and update the currently authenticated user's data. Use your publishable client key (`pck_...`) - it's safe to include in frontend code.

    **Server access type** (`X-Stack-Access-Type: server`) is for your secure backend server. It has full access over all user data using your secret server key (`ssk_...`). 

    **🚨 Security Warning**: Never use server access type or secret server keys in client-side code, browser requests, or any publicly accessible location. Always keep server keys secure on your backend.

    For more information, see the concept documentation on [StackApp](../concepts/stack-app#client-vs-server).
  </Accordion>
  
  <Accordion title="What is this 'admin' access type that I see?">
    If you'd like to build your own version of the Stack dashboard (or update project configuration programmatically), you can use the `admin` access type. These endpoints are very dangerous and you should only use them if you know what you're doing.

    For more information, see the concept documentation on [StackApp](../concepts/stack-app#client-vs-server).
  </Accordion>

  <Accordion title="How do I handle API errors?">
    Stack Auth API returns standard HTTP status codes. Common error responses include:
    
    - `400 Bad Request` - Invalid request parameters
    - `401 Unauthorized` - Invalid or missing authentication
    - `403 Forbidden` - Insufficient permissions
    - `404 Not Found` - Resource not found
    - `429 Too Many Requests` - Rate limit exceeded
    - `500 Internal Server Error` - Server error

    Error responses include a JSON body with additional details about the error.
  </Accordion>

  <Accordion title="Are there rate limits?">
    Yes, Stack Auth implements rate limiting to ensure fair usage and system stability. Rate limits vary by endpoint and access type. When you exceed the rate limit, you'll receive a `429 Too Many Requests` response with headers indicating when you can retry.
  </Accordion>
</AccordionGroup>

## Need Help?

- Check out our [Getting Started Guide](/docs/next/getting-started/setup) for initial setup
- Visit our [Concepts](/docs/next/concepts) section to understand Stack Auth fundamentals  
- Join our [Discord community](https://discord.stack-auth.com/) for support and discussions
